还在手写API文档？有那时间撸游戏、耍手机不香咩？

前言

这是一篇整合性质的文章，也可以认为是5分钟集成实现SpringBoot自动生成API接口文档(https://lupf.cn/articles/2020/11/14/1605355425671.html)的下篇，是实现真正意义上的自动化，上篇讲的是文档自动生成的过程，如果没看过，请先移步看一下上篇再来阅读此文；虽然能自动生成文档了，但是触发生成的这个动作还是人为控制的，这里就是去掉所有需要人为参与的动作；

写这篇文章的最终目的是将整个API文档自动生成周边相关的所有技术点全部都归纳整理起来；就算是你没有任何思路，顺着这篇文章，也能把其中涉及到的东西全部学会，并且可以运用到实际的日常开发中去，让你从这些琐碎的事情中抽身出来，做更加有意义的事情。

测试源码

源码 ：https://gitee.com/pengfeilu/apigcc-demo

导读

开篇有说到，这里是一遍整合性质的文章，所涉及到的周边东西，下面的系列文章中都有详细介绍；你可以根据自己的情况选择性阅读，如果你对该方案相关技术点不了解，可以参考下面的文章做完整的测试；不要被文章列表吓到了，这里只是整理的比较详细

• 第一篇，基础文章（重要！！！）

  《5分钟集成实现SpringBoot自动生成API接口文档（上篇）》 ：https://lupf.cn/articles/2020/11/14/1605355425671.html  

  这是一遍基础性文章；本文是对该文章的进一步完善，来真正意义上的做到自动化；所以可以理解为本文是该文的下篇。

• 第二篇，集成工具Jenkins

  《基于Docker 5分钟解决Jenkins环境搭建问题》 : https://lupf.cn/articles/2020/11/07/1604760642788.html

  持续集成工具；

  本文主要介绍如何通过Docker安装Jenkins；如果你会或者已经正在使用，可以忽略此文

• 第三篇，GitLab私有仓库

  《基于Docker 5分钟搭建GitLab代码仓库》 : https://lupf.cn/articles/2020/11/07/1604761653881.html  

  代码托管仓库；

  本文主要介绍如何通过Docker安装GitLab；如果你会或者已经正在使用，可以忽略此文

• 第四篇

  《Jenkins监听gitlab的提交并自动打包（详细图解）》 : https://lupf.cn/articles/2020/11/14/1605355425671.html

  本文主要介绍如何通过GitLab配置webhook，实现代码提交之后，自动触发Jenkins构建任务。

• 第五篇；Linux虚拟机

  《基于VirtualBox搭建Linux(CentOS 7)虚拟机环境（学习必备技能）》 : https://lupf.cn/articles/2020/04/04/1586001434581.html

  作用如题。如果你想进行一些测试，可以使用该方式搭建测试环境。

• 第六篇，Docker

  《CentOS 7下安装Docker及基础操作》 : https://lupf.cn/articles/2019/11/23/1574503815568.html

  本文会使用到Docker去部署api服务，所以，不了解Docker的，可以参考此文安装Docker，并了解基础的操作。

上面是相关文章的一个导读，从这里开始；正式开始讲解，如果通过GitLab + Jenkins + Docker + Apigcc实现文档自动化生成

自动化部署

图示部署过程

第一步，配置文档生成

通过 《5分钟集成实现SpringBoot自动生成API接口文档（上篇）》 ：https://lupf.cn/articles/2020/11/14/1605355425671.html  我们已经学会通过apigcc，生成了模块对应的文档，并且通过一个主页将他们整合起来了；但是这一些的生成和发布动作都存在一部分人为干预的过程，并没有完全实现自动化。下面通过几款集成工具加上相关配置，来完成去掉手动操作的部分。

第二步，将代码推送到GitLab仓库

如果不知道如何搭建和推送，可以参考《基于Docker 5分钟搭建GitLab代码仓库》 : https://lupf.cn/articles/2020/11/07/1604761653881.html   其中的示例也就是使用的本文的示例代码进行测试的。

第三步，Jenkins创建项目并绑定GitLab项目

jenkins创建一个构建项目，并将其与GitLab上的项目绑定，实现GitLab上代码的提交自动触发Jenkins的构建任务；详细可参考

《Jenkins监听gitlab的提交并自动打包（详细图解）》 : https://lupf.cn/articles/2020/11/14/1605355425671.html  其中的示例也是基于本文的示例写的。

第四步，脚本创建

• 目录 api-doc-docker

  后续一些脚本都是使用的这个目录名称

• Dockerfile

  构建用于发布api静态文件的镜像

  构建说明：

  基于nginx；会将主页的index.html文件以及创建好的静态API文件放置到容器Nginx默认目录：/usr/share/nginx/html

  COPY ./index.html /usr/share/nginx/html/ADD ./order /usr/share/nginx/html/orderADD ./product /usr/share/nginx/html/productADD ./users /usr/share/nginx/html/users

  注意，这里的文件夹名称，如./order ./product ./users需要根据自己实际的情况来调整

• stop_and_remove_old_version.sh

  用于停旧版本容器

  删除旧版本的镜像

  # 停止并删除容器api_doc_run_code=`docker ps -a | grep api-doc |awk '{print $3}' |head -n 1`if [ "$api_doc_run_code" != "null" ];then docker rm -f api-doc  echo "停止并移除容器:"$api_doc_run_codefiimage_version=`docker images | grep api-doc |awk '{print $3}' |head -n 1`if [ "$image_version" != "null" ];then docker rmi $image_version  echo "移除旧版镜像:"$image_versionfi

  查找当前运行的容器中名称包含了api-doc对应的容器id

  docker ps -a | grep api-doc |awk '{print $3}' |head -n 1

  查找镜像中名称包含了api-doc对应的镜像id

  docker images | grep api-doc |awk '{print $3}' |head -n 1

• index.html

  上篇中涉及到的主页的那个html

第五步，Jenkins中创建GitLab的全局认证用户

通俗点说，就是在jenkins中创建一个用于在gitlab中下载代码的账户

第六步，添加构建脚本

pipeline {   agent any   stages {               stage('下载源码'){           options { timeout(time: 60, unit: 'SECONDS') }           steps {                git branch: "master",               credentialsId: 'gitlab_root_user',               url: 'http://192.168.1.222:880/root/apigcc-demo'           }       }       stage('编译DOC'){           steps {                sh '''                  cd ./order                 mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs                                    cd ../product                 mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs                                    cd ../users                 mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs                '''           }       }       stage('docker打包'){           steps {                sh '''                  echo "${BRANCH_NAME}"                                  cp -r ./order/target/docs/order ./api-doc-docker                  cp -r ./product/target/docs/product ./api-doc-docker                  cp -r ./users/target/docs/users ./api-doc-docker                  ls -l ./api-doc-docker                                    sh ./api-doc-docker/stop_and_remove_old_version.sh                                   docker build ./api-doc-docker/ -t apigcc-api-doc:master                                  '''             }       }       stage('重启容器'){           steps {                sh '''                 docker run -d --restart=unless-stopped -p 7777:80 --name=api-doc apigcc-api-doc:master                '''             }       }           }   post {       success {            sh '''            git_author_name=$(git show -s --pretty="%an<%ae>")            git_push_time=$(git show -s --pretty=%ad)            echo "${JOB_NAME} has builded at $git_push_time by $git_author_name "            '''       }       aborted {            sh '''            git_author_name=$(git show -s --pretty="%an<%ae>")            git_push_time=$(git show -s --pretty=%ad)            echo "${JOB_NAME} has builded timeout at $git_push_time by $git_author_name "            '''       }   }}

• 下载源码

  git branch 指明分支名称

  credentialsId  上面创建的全局用户对应的那个id

  url  项目在GitLab仓库中的地址

• 编译DOC

  cd ./ordermvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs                  cd ../productmvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs                  cd ../usersmvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs

  以shell脚本的方式进入到各个模块中（具体的模块名称可以根据实际情况调整），并执行打包指令，打包编译出每个模块的文档

• docker打包

• 统一文件目录

  cp -r ./order/target/docs/order ./api-doc-dockercp -r ./product/target/docs/product ./api-doc-dockercp -r ./users/target/docs/users ./api-doc-dockerls -l ./api-doc-docker

  为了方便后续构建镜像，将各个模块打包出来的api静态文件，统一拷贝的api-doc-docker

• 停止移除老的容器和镜像，创建新的镜像

  # 通过脚本停止、删除旧的容器以及其对应的镜像sh ./api-doc-docker/stop_and_remove_old_version.sh# 基于生成的最新api静态文件，构建一个新的docker镜像docker build ./api-doc-docker/ -t apigcc-api-doc:master

• 重启容器

  docker run -d --restart=unless-stopped -p 7777:80 --name=api-doc apigcc-api-doc:master

• 最后的日志

  输出打包后的结果

第七步，自动构建测试

• 添加接口前的文档

• 添加一个订单修改的接口

  /** * 修改订单 * @param orderInfo 修改的订单信息 * @return 是否修改成功 */@PostMapping("update")public Integer update(@RequestBody OrderInfoRo orderInfo){    return 1;}

• 提交并自动构建

  由于太长了，gif缺失了后面的一小段构建成功的部分

• 构建成功后刷新文档页面

总结

到此，一个完全自动化构建部署的API文档生成方案就介绍完了，虽然这个过程稍微复杂一点点，但是结合在实际的使用过程中，发现这种方式更加的灵活、便捷；除了首次部署构建的过程会带来一点小小的负担，但是部署完成之后，对代码的侵入性几乎为0，代码写完之日就是咱出文档之时。

更多思考

• 多项目的问题

  上面的演示使用的是多模块的方式，日常开发中有多项目的情况，针对多项目，也只是多模块的一个变种；那么就得根据个人实际的情况去调整调节各个模块的发布情况；也只需要基于上面做一些调整

• jenkins和部署的不在同一机器上

  可能需要将文档发布到jenkins外的其他机器；那就需要将Docker镜像推送到私有或者其他托管的镜像仓库；然后通过jenkins在其他机器上更新下载镜像；并启动容器；这里有一篇基于《阿里云托管Docker镜像仓库》 ：https://lupf.cn/articles/2020/11/12/1605160545846.html 的教程；也可以使用harbor搭建私有镜像仓库，《基于Docker安装Harbor搭建Docker私有仓库》 :https://blog.csdn.net/lupengfei1009/article/details/105247304